ParcelAddress API

(0 reviews)

Australian Address Lookup

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parceladdress/2.0/australia/addresses/{address_id}
Production:
https://api.nzpost.co.nz/parceladdress/2.0/australia/addresses/{address_id}

Resource Description

This resource is intended to be used in conjunction with the Get International Address Detail resource. The Australian Address Lookup returns the detailed information for a single address identifier for an address in Australia. This resource is Alt text. The details returned from Google Places is mapped to NZ Post standard address fields. The Australian Address Lookup resource is useful to the merchant who sends a regular volume of parcel to Australian destinations and also consumes the ParcelLabel functionality.

Resource Information

AttributeDetail
Response FormatJSON
Requires AuthenticationYes
Rate Limited15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

Please note that all request parameters should be in lower case.

Request Parameters

Field NameDescriptionMandExample
address_idInternational address identifier used by Google Places.YesEjAzODAwIExhIFBhc2FkYSBBdmUsIExhcyBWZWdhcywgTlYsIFVuaXRlZCBTdGF0ZXM

Sample Request

https://api.nzpost.co.nz/parceladdress/2.0/australia/addresses/ChIJN1t_tDeuEmsRUsoyG83frY4%26key%3DAIzaSyAC711805j5JJgCpY7RV662jayqffVS-jY

Response Parameters

The following lists the required fields in the Australian Address Lookup response message:

Field NameDescriptionMandExample
successReturns if request is successfulYesfalse
addressAddress object with address detailsY if success = true"address": {}
message_idThe unique message identifierYesec608f40-2a8b-11e5-a9c0-025c481d35ef

Address Object

The following lists the required fields in the address object.

Field NameDescriptionMandExample
street_numberThe street address numberNo139
streetThe name of the streetNoMitchell St
suburbThe name of the suburb the address residesNoLarrakeyah
stateName of the Australian stateNoNorthern Territory
state_codeCode for the Australian stateNoNT
postcodeThe postcode associated with the addressNo0820
longitudeThe GPS longitude coordinate if the data existsNo130.832234
latitudeThe GPS latitude coordinate if the data existsNo-12.456088
countryThe name of the country the address residesNoAustralia
country_codeThe code for the countryNoAU
formatted_addressThe "human readable" addressNo139 Mitchell St, Larrakeyah NT 0820, Australia

Error Response Elements

Field NameDescriptionMandExample
successReturns if request is successfulYesfalse
errorsError object with error detailsYes if success =falseSee Error Object Parameters below
message_idThe unique message identifierYesec608f40-2a8b-11e5-a9c0-025c481d35ef

Error Object Parameters

Field NameDescriptionExample
codeError code where first 3 digits are http status code, last three digits identify error type400002
messageDescription of error codeInvalid Parameter(s)
detailsDescription of specific errorAddress prefix must be at least 4 characters, not including spaces at the beginning or end.

HTTP Status Codes

Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request

CodeMessage
200Success
400Bad request
401Unauthorized
403Forbidden
409Invalid request
500System unavailable

Error Codes

CodeMessage
200001Partial results returned, not all system(s) have responded
200002All sources responded, data may be incomplete
400001Parameter(s) missing
400002Invalid parameter(s)
400003Non mutually exclusive parameters detected
401001Unauthorised access, please contact administrator
500001General Exception
500002System(s) offline

Sample Response

Sample success response:

{
   "success": true,
   "address":    {
      "street_number": "139",
      "street": "Mitchell St",
      "suburb": "Larrakeyah",
      "state": "Northern Territory",
      "state_code": "NT",
      "postcode": "0820",
      "longitude": 130.832234,
      "latitude": -12.456088,
      "country": "Australia",
      "country_code": "AU",
      "formatted_address": "139 Mitchell St, Larrakeyah NT 0820, Australia"
   },
   "message_id": "27009370-2a69-11e5-a9c0-025c481d35ef"
}

Sample failure responses:

{
   "success": false,
   "errors": [   {
      "code": "40002",
      "message": "Invalid Parameter",
      "details": "International Address ID is invalid"
   }],
   "message_id": "ec608f40-2a8b-11e5-a9c0-025c481d35ef"
}

{
   "success": false,
   "errors": [   {
      "code": "40002",
      "message": "Invalid Parameter",
      "details": "International Address ID is not an Australian Address"
   }],
   "message_id": "ed0819e0-2a8b-11e5-a9c0-025c481d35ef"
}

Reviews